TWINExtract 0.2
+-+-+-+-+-+-+-+
  Here it is!  This tool will extract telemetry data, along with textures, from stages and possibly other things in TWINE (N64). You'll need an unbyteswapped, uncompressed TWINE (N64) NTSC North American ROM image, reading N07E in the header.  This is done with a series of tools, but so long as you can use batch files the whole process is (mostly) automated.  To start, use TWINExtractor.exe

Usage:
TWINExtractor.exe <filename.rom> [-S*] [-C] [-E] [-I] [-G] [-O] [-N] [-A] [-H]

  TWINExtractor.exe is best used from the command line to ensure the current folder is the working directory.  You can optionally mention the ROM file on the command line, as well as one or more of these option flags.  By default, Labyrinth is extracted, but this can be changed with the -S command.
-S<#> or -S<name>	set stage to be extracted
	You can either give a stage number or use one of the names in this list:
	<#>	<name>		<stage>	
	0	Air		Air Raid
	1	Midnight	Midnight Departure
	2	Courier		Courier
	4	Castle		Castle
	7	Istanbul	Istanbul
	8	Crate		Crate Yard
	9	Field		Field of Fire
	11	Masquerade	Masquerade
	12	Forest		Forest
	16	Thames		Thames Chase
	18	Fallen		Fallen Angel
	19	Merchant	Merchant
	20	King		King's Ransom
	21	MI6		MI6
	22	Silo		Silo Surprise
	23	Flashpoint	Flashpoint
	24	Labyrinth	Labyrinth
	25	Cold		Cold Reception
	26	Sky		Sky Rail
	28	Turncoat	Turncoat
	29	Sink		A Sinking Feeling
	31	Frostbite	Frostbite
	32	Submarine	Submarine
	33	Meltdown	Meltdown
	34	Under		Underground Uprising
	38	Night		Night Watch
	39	Hidden		Hidden Volcano
	40	Walkways2	City of Walkways II
	41	Walkways1	City of Walkways I
	Only numerical values 0-507 (0x1FB) are valid
-C	by default, intermediary files are usually cleaned away.  This disables the function
-E	toggle this if you do not want to immediately launch the batch file StartHere.exe creates
-I	set this to inhibit image extraction if you have already extracted the required samples
-G	set this to inhibit geometry extraction (grab only images)
-T	produces targas (.tga) instead of bitmaps (.bmp)
-O	set to stop wavefront objs from being created.
-N	(not yet implemented)
-A	uses absolute positions in extracted geometry instead of relying on their own relative coordinates
-H	displays a short help that outlines these flags


  TWINExtractor.exe will create a batch file that will call TWImages.exe and TWelemetry.exe, which extract images and telemetry respectively.  These in turn will also produce batch files that will assist in extracting the various files needed, decompressing them, and processing them into something useful.

@_@

  Here's a short list of the other programs that are called, what they do, and the stuff they accept.
EDLdec.exe <filename>
	Decompresses EDL files
NibbleSwapper.exe  <filename> [offset]
	Swaps nibbles in certain image types.  Can offset the start position in the file with an optional offset value.
TWImages.exe <filename.rom> [-C] [-B] [-T]
	Sets up a batch file that decompresses image data files and sends them to IMGFormat.exe.
	Requires 'objects' already be extracted by StartHere.exe.
	Optionally accepts:
	-C	do not clean intermediary files
	-T	output targas (.tga)
	-B	output bitmaps (.bmp)
IMGFormat.exe <basename> <index> [mode]
	Sets up a batch file that compiles each image, swaps nibbles, generates a basic .mtl file, and generates a size binary file.
	'basename'  is the name of the *.img, *.iimg, *.pal, and *.ipal files created by TWImages.exe.
	'index' is the original ROM index number for the resources, usd to name the output images.
	Requires '<basename>.img', '<basename>.img', '<basename>.pal', and '<basename>.pal'.
	Optionally accepts:
	mode	0 for bitmap (.bmp) output, 1 for targa (.tga).  The default is 0.
N64toTGA.exe <filename.bin> <type> [size.bin index]
N64toDIB.exe <filename.bin> <type> [size.bin index]
	Creates a targa or bitmap file from the provided binary and a conversion type.  Outputs 'filename.tga' or 'filename.bmp'.
	Does not set the width and height unless you declare a size binary and index for the data in it.
	'filename.bin' is a prepared binary.
	'type' must be one of these types:
		0 -32bit rgba
		1 -24bit rgb
		2 -16/15bit rgba
		3 -16ci  32bit samples
		4 -16ci  24bit samples
		5 -16ci  16bit samples
		6 -256ci 32bit samples
		7 -256ci 24bit samples
		8 -256ci 16bit samples
		9 -16bit IA (8:8)
		10-8bit IA  (4:4)
		11-4bit IA  (3:1)
		12-8bit I
		13-4bit I
		You can also tack +64 to flip the image horizontally or +128 to flip vertically.
	N64toDIB.exe only:
		0x0300 -bitmapX format, which amounts to declared bitmasks for each color component
		0x1000 -16bit images only: 1:5:5:5 output
		0x2000 -16bit images only: 5:6:5 output
		0x4000 -16bit images only: 5:5:5:1 output (N64 native format)
	Optionally accepts 'size.bin' + 'index', both of which must be present when a size.bin is used.
	'size.bin' is the width and height binary returned by IMGFormat.exe.
	'index' is the entry number in 'size.bin' to extract the data from.
TWelemetry.exe <filename.rom> [-1] [-2] [-A] [-C]
	Sets up a batch file that decompresses geometry data files and sends them to TWINEdle.exe or TWINEobj.exe.
	Requires 'objects' already be extracted by StartHere.exe.
	Optionally accepts:
	-1	disables wavefront obj output
	-2	disables N64 DLE output (not yet implemented)
	-A	use absolute, not relative, positions for final objects
	-C	do not clean intermediary files
TWINEobj.exe <basename> <material> [xpos] [ypos] [zpos]
	Generates a wavefront obj and material file from TWINE's telemetry data.
	'basename' is the name of the *_v, *_g, *_c, and *_t files used to form the object
	'material' is the ROM offset name of an image bank's .bin file, used to determine the proportions of the textures
	Requires matching '<basename>_v', '<basename>_g', '<basename>_c', '<basename>_t', and <material>.bin files
	Optionally accepts floating-point x, y, and z offsets for to offset object positions.

=_=

  Caveats:
1) The textures aren't mapped properly yet, but they're on the right surfaces and that's half the battle.
2) Not all possible image types and microcode commands are accepted yet.  Cross your fingers.
3) It doesn't always get rid of all the files it should have gotten rid of.  Sorry.  It is mostly clean, at least...
4) Sometimes images are present that are not used as materials.  They give the proportions as 0, and these programs don't usually get the actual proportions right.  Seriously though, this only occurs when they don't use the image, and the only ones I've seen where image data was present are solid white materials and entirely transparent ones.  So, no big loss in other words.

-_-

  As it stands now...
+ Multiplayer Stages:
  All seem to be outputting correctly, even that beta one.
+ Unlisted Values:
  These are objects, characters, cutscene locations, and various other resources.  Most of these resources will extract.
- All Solo Stages:
  TWINEobj.exe will fail at least once in every solo stage.  However, extraction will continue after it does so.  All's well.
- Midnight Departure:
  One image will cause bad things.  You can ctrl+break to kill the IMGFormat.exe window (continue the batch file after this) and it should continue normally.

+

  Source is provided for most of the tools in the source folder.  It isn't well written and no real documentation is present, but then that's always the case, isn't it?

+_+

-Zoinkity
(nefariousdogooder@yahoo.com)

#_#

Release Log:

8:14 PM 11/28/2008	0.2	added N64toDIB.exe, updated a few things
7:28 PM 11/19/2008	0.1	initial release
